Tools Plus is a library of routines that simplifies programming an Apple Macintosh computer, and significantly reduces the time it takes to write and debug a program. With Tools Plus, you program at a much higher level when creating, maintaining, and working with a user-interface, so you can develop applications…
• more easily
• more quickly
• with less source code
• with fewer bugs
• and with more features
than if you use ordinary Pascal. Tools Plus libraries can be used by programmers developing applications in THINK C or THINK Pascal.
An Overview of Tools Plus
`````````````````````````
To describe Tools Plus in a single sentence, it’s a “user-interface maintainer and event translator and processor.” Its main function is to let you create a user-interface without actually having to maintain it. A simple example of this is the Apple menu. With Tools Plus, you can give your application full reign over desk accessories just by creating the Apple menu with the AppleMenu routine. Tools Plus automatically takes care of any activity pertaining to desk accessories, such as when the user selects a desk accessory from the Apple menu, repositions the accessory by dragging it, clicks buttons or types in the accessory, copies and pastes text in the desk accessory, and eventually closes it. All this is handled automatically by Tools Plus (you don’t have to write any code for it).
Tools Plus’s features integrate with each other in accordance with the User-Interface Guide-Lines found in Inside Macintosh. An active Editing Field, for example, automatically intercepts and processes key-strokes from the keyboard. An Editing Field’s text can also be affected by the Edit menu, which lets the user Cut, Copy, Paste, and Clear the text, as well as transfer text between your application and other applications and desk accessories via the clipboard. The Edit menu is automatically affected by what goes on in the active Editing Field: when an insertion point is in the field, the Edit menu’s “Cut” and “Copy” selections are disabled, since no text is selected for cutting or copying. You can see how this frees you (the programmer) to do more important things, like writing programs!
The heart-beat of Tools Plus is the polling routine, which is called by your application (instead of calling the Macintosh toolbox’s GetNextEvent or WaitNextEvent) to obtain events generated by the user, such as typing or mouse-clicks. In fact, all events are obtained this way. The big difference here is that Tools Plus’s polling routine does everything it possibly can before informing your application of an event. Many events are processed internally and are never reported to your application, such as when the user types in an Editing Field (because the field automatically processes the typing). Other events are reported to your application, such as when the user clicks a button.
In contrast to other polling routines such as GetNextEvent or WaitNextEvent, Tools Plus’s polling routine translates the Macintosh’s events into something your application can use right away. So instead of getting a low level “mouse down” event, your application gets a “high-level” event such as “the ‘Save’ button was clicked in the ‘Add Customer’ window.”
The following example illustrates the difference between ordinary C or Pascal programming, and a program written with Tools Plus. The left column represents the steps a traditional program has to take to detect and process a simple event, whereas the right column has the benefit of Tools Plus. Note that the left column is highly simplified!
Ordinary C or Pascal Programming Programming with Tools Plus
2 Determine the type of event (a = Button Number 3 was clicked in
“mouse-down”) Window Number 2
3 Determine its location (a
window’s content region)
4 Determine where in the window (a
“control”)
5 Track the mouse in and out of the
control
6 If the mouse button was released
inside the control’s region,
report that the control was
selected. Otherwise ignore the
entire event.
-----------------------------------
= Mouse-down event
in a control (handle is known)
in a window (pointer is known)
Of course, additional steps could be taken in traditional C or Pascal to obtain a window number and button number, but at the expense of more programming.
The Tools Plus Advantage
````````````````````````
There are many advantages to using Tools Plus when you are writing a Macintosh application:
• Tools Plus routines work seamlessly with Finder, MultiFinder (pre-
System 7) and System 7.
• Unlike “code generators,” Tools Plus does not demand that you adhere
to a rigid design or cumbersome application constraints. Tools Plus
fits in with your programming style, weather your code is procedural
or object-oriented.
• You can use the same Tools Plus libraries and support files
regardless if you are compiling your application for a plain 68000
processor, or optimizing it for 68020, 68030, or 68040 processors,
and/or optimizing it for a math co-processor (68881, 68882 or 68040.)
• Instead of using many of the Macintosh toolbox’s routines, you’ll use
relatively few Tools Plus routines. You will find it easier to
program when you need to use fewer routines to accomplish a given
task.
• You can typically create elements of the Macintosh’s user-interface,
such as windows, buttons, check boxes, scroll bars, pull-down menus,
list boxes, editing fields, etc., with a single Tools Plus routine.
Tools Plus makes creating a user-interface a breeze.
• The interrelationship between Tools Plus objects is automatically
maintained. An illustration of this is when the user is typing in a
field in your application, goes to the Apple menu and selects the
calculator, performs some calculations and selects the Edit menu’s
Copy command, then goes back to your application and chooses the Paste
command to paste the calculator’s answer into the field.
You, as a programmer, don’t have to code anything to account for the
interdependencies between your application’s editing fields, the Edit
menu, the Clipboard, the Apple menu, and the calculator.
• Tools Plus makes it easier to work with user-interface elements by
referencing them by number. In contrast, Macintosh toolbox routines
use pointers to reference windows and handles to reference buttons and
scroll bars. Your application will be easier to write with Tools Plus
because there will be less to remember.
• Tools Plus routines are self-maintaining. For example, after you
create a button, you can forget it. Tools Plus will let you know when
that button is selected by the user.
• The revolutionary Event Translator in Tools Plus reports usable
events. An example of this is telling your application “the Cancel
button in the Search dialog was selected.” This is far simpler than
decoding event messages and tracking controls, handles and pointers,
as required with ordinary C or.
• Tools Plus routines do a lot of work for you. A single Tools Plus
routine can save you writing hundreds of lines of source code making
dozens of calls to Macintosh toolbox routines, so you’ll end up
writing considerably less source code.
• Tools Plus takes care of most of the Macintosh’s user-interface “house
keeping” by automatically handling desk accessories, mouse and
keyboard activity, translating and processing events, and telling your
application what the user and system are doing. You can focus on
writing your application instead of maintaining the user-interface.
• With Tools Plus, you will have far fewer bugs because you’ll be
writing considerably less code. Applications written with Tools Plus
are shorter and simpler to debug and modify, and they also have more
readable source code.
• Tools Plus is efficient: it requires little memory or disk space, and
it executes quickly.
• Macintosh standards have been observed as described in Inside
Macintosh. This helps ensure that your finished application behaves
in a way that all Macintosh applications should.
• Tools Plus is easy to learn and use. If you can program in C or,
you can use Tools Plus.
• Many aspects of the Macintosh’s impeccable user-interface, which may
have been excluded due to their complexity, can be easily incorporated
into your application.
• There are no runtime costs for Tools Plus. That means registered
Tools Plus users can distribute application they have written with
Tools Plus without having to pay additional fees.
• The Tools Plus libraries are constantly being expanded, enhanced and
optimized based largely on users’ requests, so you’ll be benefiting
from others’ innovations.
• Tools plus is identical for both C and Pascal, so if you get involved
with the other language, you take your knowledge of Tools Plus with
you.
• Source code for the Tools Plus libraries is available.
Who can benefit from Tools Plus
```````````````````````````````
Just about anybody writing an application on the Macintosh in C or can benefit from using Tools Plus. It’s useful to different people for different reasons:
• Novice programmers can start developing applications more readily and
with greater confidence. The task of programming is simplified to
produce quicker results with fewer bugs. And you don’t have to learn
a resource editor (such as Apple’s ResEdit) before you start using
Tools Plus.
• Seasoned programmers can use Tools Plus to develop an application in
less time and with fewer bugs.
What kind of applications can be written with Tools Plus
Tools Plus does not limit you to writing certain kinds of applications, in that it does not preclude you from exercising your technical or creative skills on the Macintosh. It merely helps simplify and manage the user interface and event processing that is so prevalent in Macintosh programs. Varying programming needs are addressed by Tools Plus:
• Quick and Dirty applications can be written in less time. These
programs can have all the features of finished Macintosh applications,
which makes them easier to work with.
• Full fledged applications that are suitable for shrink-wrapping can be
created using Tools Plus.
• Just about any program can be written more quickly and with less
effort by using Tools Plus.
What is Tools Plus not suitable for
```````````````````````````````````
Tools Plus is intended for application developers. It was designed to be the event processing and translating engine within an application, so it definitely cannot be used to create the following:
• Drivers, control panels, INITs or system extensions
• CODE segments that can be incorporated into other applications, such
as 4th Dimension
• Desk accessories. You can still use Tools Plus to write an
application that looks and feels like a desk accessory while running
under System 7.
System Requirements
```````````````````
Computer
````````
Tools Plus makes extensive use of ROM routines that are found only in the 128k ROMs (version 117) or higher. Applications written with Tools Plus will run on the Macintosh 512KE (the “E” stands for enhanced with the new ROMs) or higher. They will not run on a Lisa (also called a Macintosh XL), Macintosh 128K or a standard Macintosh 512K computer.
Compiler
````````
Tools Plus can be used by programmers developing in THINK C 5.0.4 or higher, or THINK Pascal 4.0.2 or higher. You may be able to use older versions of either compiler, but we recommend the latest version.
System
``````
Applications created with Tools Plus can run under System 6 (optimally 6.0.8) or System 7. We recommend that you use the newest system version because Apple has fixed various bugs and many features have been added to the newer versions.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 requires System 5.0 or higher. THINK Pascal 4.0 requires System 6.0.5 or higher. Consult your compiler’s User Manual for details.
Note: Registered users will receive a special version of Tools Plus that is compatible with System 4.2 or higher.
Memory
``````
Applications created with Tools Plus can run with as little as 64k, depending on the complexity of your application. The overhead associated with Tools Plus is in the neighborhood of 50k.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require 2MB of RAM when using System 7. Consult your compiler’s User Manual for details.
Disk Space
``````````
Tools Plus’s libraries and header or interface file require about 200k of disk space for C, and about 125k for Pascal. When compiled, Tools Plus will add less than 50k to your application’s size.
While developing applications using Tools Plus, you will still have to observe the requirements and limitations of your development environment. THINK C 5.0 and THINK Pascal 4.0 both require about 2MB of disk space.
Finished Applications
`````````````````````
Please be aware that you, as a programmer, have the capacity to write applications that have requirements far in excess of Tools Plus’s minimum system requirements. It’s possible that you may choose to write a program that requires a math co-processor, System 7, 20 megabytes of RAM, and a pair of 20 inch color monitors. Be aware that your finished application will likely have needs that exceed Tools Plus’s minimum requirements.
Tools Plus Source Code and Site Licensing
`````````````````````````````````````````
Complete source code is available for the set of Tools Plus libraries. This offer is intended for (but not limited to):
• entities that must assure their autonomy by not relying on closed
third party products
• developers that need to broaden Tools Plus’s scope
Tools Plus source code is heavily commented. Pricing and Source Code Licensing information can be obtained by contacting Water’s Edge Software. Water’s Edge Software also offers Site Licenses at an appropriately reduced pricing structure. Please contact Water’s Edge Software for details.
Assumptions made when writing this manual
`````````````````````````````````````````
Several assumptions have been made when writing this manual:
• You are already a C or Pascal programmer, or are learning to be one on
your own. This manual does not teach you how to program in C or
Pascal, nor does it teach you how to use the Macintosh’s toolbox
routines. It merely teaches you how to use Tools Plus.
• This manual makes no attempt to teach you how to use THINK C or
THINK Pascal. Please consult your THINK C or THINK Pascal User Manual
in such matters, or contact the manufacturer, Symantec Corporation.
• This manual makes no attempt to teach you how to use ResEdit, or any
other application or tool that is part of your development
environment.
• You already know how to use the Macintosh, and are familiar with its
terms such as clicking, dragging, selecting, etc.
• This manual does not assume that all programmers and users are male.
For the sake of easier reading, the term “he” implies either gender
within this manual.
Convensions used throughout this manual
```````````````````````````````````````
1) Each Tools Plus routine is documented with both a C header and
Pascal interface.
2) Source code examples are given in Pascal, just like Inside
Macintosh. In situations where the C source code differs (usually
due to differences in record structure), an example is also provided
in C.
3) The Pascal terms function and procedure are used throughout this
manual. For the benefit of C programmers, a function is a routine
that returns a value. The following table provides an example:
C “Procedure”: pascal void DeleteListBox(int ListBox);
Pascal Function : function FirstWindowNumber: integer;
C “Function” : pascal int FirstWindowNumber(void);
4) Important information is highlighted with notes and warnings...
Note: A note that may be interesting or useful (don’t skip these)
Warning: A point you need to be cautious about.
5) This manual is not intended to replace Inside Macintosh or its
equivalent. It does not detail the fundamentals of Macintosh
programming, such as screen versus window co-ordinate systems (local
versus global), commonly used structures (points, rectangles,
grafPort, etc.), using the Macintosh toolbox, etc.
6) For the benefit of new programmers, portions of this manual address
the basics of building a Macintosh application, such as some
differences between Finder and MultiFinder and how to complete a
double-clickable application.
Software Updates
````````````````
Registered Tools Plus users are entitled to take advantage of our Software Update Program, which offers free updates and updates at reduced prices. We recommend that you periodically check the Water’s Edge Software bulletin board on CompuServe (see the Technical Support chapter for details) to determine the latest version and information on how to upgrade.
Water’s Edge Software is enhancing Tools Plus on an on-going basis by optimizing code and adding new features. We will inform registered users of newly available updates either by mail or by CompuServe (if you tell us your CompuServe account, we will send you upgrade information electronically).
Note: In order to ensure uninterrupted software update notification,
please inform us in writing if your mailing address or CompuServe
account changes.
Your Development Environment
````````````````````````````
This manual makes no attempt to teach you how to use your development environment, THINK C or THINK Pascal. Please consult your THINK C or THINK Pascal User Manual in such matters, or contact the manufacturer, Symantec Corporation.
Every Macintosh developer should have a copy of ResEdit, Apple’s resource editor application. It’s easy to use, indispensable, and best of all, free from your Apple dealer. Always get the latest version (2.1.1 at this writing), since it’s always being upgraded and improved. Beginners can get by without ResEdit, but you won’t want to.
For your information (recommended reading)
``````````````````````````````````````````
For any Macintosh programmer, we suggest you either own or have access to the entire series of “Inside Macintosh” technical reference guides by Addison Wesley. They are the definitive Macintosh bible for programmers of any caliber. They’re worth their weight in midnight oil if you want to get into serious Macintosh programming.
Another indispensable tool is THINK Reference, an on-line reference manual for C or Pascal programmers. It describes all the Mac’s data structures, variables, constants, functions and procedures. It also has valuable programming tips.
To program a Macintosh, you’ll have to know the basics of the Macintosh toolbox. We recommend the following:
• Get familiar with QuickDraw by reading chapter 6 of Inside Macintosh
Volume I (or equivalent). This section details drawing in the
Macintosh’s graphic environment.
• Get familiar with the Font Manager by reading chapter 7 of Inside
Macintosh Volume I (or equivalent). This section deals with drawing
text on the Macintosh’s screen
• Have a working knowledge of the Macintosh’s Memory Manager (chapter 3
of Inside Macintosh Volume I, or equivalent). This section deals with
pointers, handles, and memory fragmentation.
• The thing that differentiates a good Macintosh application from the
rest of the world is that a user will find the program easy to learn
and use. These benefits can be attributed greatly to a consistent and
well-designed user-interface. Learn the dos and don’ts of graphic
user-interface (GUI) design, then learn some more! Chapter 7 of
Inside Macintosh Volume I introduces you to the Macintosh’s GUI and
it’s standards. Another good way of learning is to get exposure to
(and become familiar with) a wide range of Macintosh applications.
You’ll spot the good ones and the not so good ones after a while!
